Help:Infoboxes/Migration walkthrough
This is a step-by-step guide to fast, easy conversion of classic wikitext infoboxes to . While it is impossible to cover every single type of infobox — as some infoboxes are more exotic than others — you should find that these instructions are broadly applicable to most situations. It is written for people of all skill levels, and definitely is not intended only for use by . It should be a good guide to building good infoboxes from the beginning. There are "best practices" and portability principles scattered throughout for additional insight. Fundamentals Before you get started, you should ideally be familiar with: * basic * the notion of CSS selectors and properties * the fact that the terms classic infobox, non-portable infobox, and NPI or nPI all mean the same thing Because Portable Infobox markup is actually XML, it'll also help to know what's meant by "XML well-formedness". However, since migration with the migration naturally results in XML being well-formed, this is typically more of a diagnostic skill than one actively needed to make Portable Infoboxes. Step 0: Finding your infoboxes Before beginning the conversion process, you first have to figure out which templates need to be converted. This means finding all your templates. If you're lucky, most of them will be in a category, often called Category:Infoboxes or Category:Infobox templates. But sometimes infoboxes won't be filed away neatly. That's when you have to look for templates by classification. When in doubt, examine what the template's intended role is. The best place to start is to look at Special:Insights/templateswithouttype. You may sometimes see Vanguard members shorthand "unclassified templates" as "UTs". * Look at each template entry in Templates Without Type that seems like it may be an infobox. If it is a complete and self-contained infobox, classify it as Infobox. If it is a component to build part of an infobox, that is usually Data (if it's changing the actual text) or Design (if it's changing how the content or element looks). * Change the classifications of those templates by selecting (clicking or tapping) the classification (which appears as a link near the Template page's title) or using the "k" key shortcut. A partial window panel (called a "modal") will appear to select the new classification. * If you have several templates put into a category, you can use the "Bulk template classification" tool to massively classify them. The tool can be only used by local admins or some volunteer groups, such as VSTF and Vanguard. NOTE: Changes in classification will not usually appear in Insights until the next day, as they are cached once daily. Non-Insights Special pages, like Special:Templates, are updated more frequently (but not in real-time). Step 1: Insights Special:Insights/nonportableinfoboxes is the spine of infobox porting work for a community. It also will sometimes show false positives (or templates that are not really infoboxes, or appear in no articles). Scroll down to the bottom of the Special:Insights/nonportableinfoboxes list and classify templates that appear on 0 articles as Non-Article, or other appropriate classification. As Template Documentation pages may appear in this list — but by definition are not intended for article pages — Non-Article is the proper classification. See Step 0 for more detailed instructions. Inventory of potential themes and variations The first part of this is fairly simple. For the infoboxes to be migrated, look at the articles where the templates are in place with Special:WhatLinksHere (found on the Insights page as "Used on X articles". Examine the general visual style of each template and note if they use a consistent style or "look", or if they look mostly the same as each other (but could be made consistent), or if they look completely different. Each major difference in style will potentially become a theme later. Be sure to note what components are consistent (such as color or rounded corners) across most themes, so that those traits can be added to the default .portable-infobox style when you create it. The second part is potentially very technically challenging, but is necessary for a consistent replacement of a community's classic infoboxes. The easiest way to do this is to look at the source code for the classic infobox for places where the styling is changed by a parameter, such as class=" }" or style="width: }; background-color: }". In that last example, bgcolor is likely to be used as a theme-source parameter. Step 2: The "Convert!" button, and what it does and doesn't do When a template is classified as Infobox but does not use the Portable Infobox syntax, a "Convert!" button will appear in the Insight page next to the template (and in the Template page's rail). This button triggers a migration tool that partially converts the non-portable infobox into a Portable Infobox draft. The tool will usually detect all variables used by a classic infobox and convert them into appropriate Portable Infobox syntax. It is familiar with the most commonly used code patterns for labels, default values, and attempts to recognize and convert them for Portable Infobox roles. Though this tool is useful and can do a major part of the migration itself, there will usually be some work which has to be done manually. Most of variables will be converted into tags, usually with a : the migration tool can not always distinguish wikitext parameters intended for use as and , and does not detect other elements of the infobox (such as headers, captions, default values, and other elements not using variables). More complex infoboxes that need themes, groups, smart groups, or tags won’t be converted by the migration tool either - these will have to be done manually, based on the original code used by the classic infobox. This tool can still be a way to start the conversion of an infobox, giving a starting point for the final Portable Infobox code - but a lot has to be done manually. Step 3: Copying the accessory code (noinclude and includeonly) Templates work by transclusion - insertion of a source template into any target article. Often enough, some parts of a template aren’t useful in all cases, so we use transclusion control tags to control that: ;: hides content within tag in target article :Often enough, a template will need certain sections hidden within articles. Documentation, infobox previews and template categories are good examples of this. ;: hides content outside tag in target article :This tag is rarely used but quickly separates an infobox from the other template contents. ;: hides content within tag in source template :The infobox itself, accompanying article categories, and hatnotes are also likely to be hidden on the template page itself. This helps prevent bugs with nPI detection. Keeping a vital part of the old infobox The original non-portable infoboxes will likely be comprised of two parts: the infobox table itself, and documentation, categorisation, navigation and other supporting information outside the table. It will often look like this: Category:Infoboxes Copy everything that comes both before and after the main body of the NPI code. That is, copy everything that's above and below the . In the new PI's code, replace the automatically-generated documentation in the PI with what you've just copied from the old NPI. In the above example: Category:Infoboxes should be used to replace any automatically-generated documentation on the NPI. Step 4: Translate the layout and groups of the classic infobox Because of the way some classic templates are coded, wikitext parameters may be interpreted out of order, or were never intended to be visible at all. The general shape and structure of these infoboxes is not detected with the migration tool. The best way to shape it properly is to go from top to bottom and start placing items into the proper order and groups. Portable Infoboxes feature automatic hiding if no value is supplied, so additional code to hide these data items is not necessary. In fact, if a has a inside and no items of the group have values, the header will not display. NOTE: Many communities define values as "Unknown" in their infoboxes when no value is given. While acceptable, this is not ideal (and tends to produce visual clutter) unless a strict horizontal grid layout is required, which should use the show="incomplete" function. Data types Is it image, title, data, navigation, header, etc? This is not always straightforward. * </nowiki></kbd> handles titles, and those titles do not feature visible labelsEven if labels do not display in articles (as is the case for </nowiki></kbd> and ), they do display in VisualEditor to facilitate editing. does not have a label function.. To be truly data-ready, it should also handle alternative titles, such as those in other languages, title translations, or subtitles. In CSS, it's easy to style secondary titles with something like .pi-title ~ .pi-title ** Many infoboxes are autogenerated with . To maintain the cleanest possible code, this should be altered to when possible. ** Titles by language should be consolidated into a single data item where they are equivalent, such as kanji / kana / rōmaji representations of the same titleA common pattern we see a lot is a Japanese-language title presented in two or three forms: kana, kanji, and rōmaji. Ideally, these use a single element formatted and broken into spanned text, such as } }|( })}} }|( })}}.The element should not be used for tooltips, as this is an accessibility violation. The should be used for abbreviations with titles and should be used (without a title attribute) to specify a foreign language term.. A visual indicator of what language is being used is not typically required, though using a flag to represent a language is a bad practice; if a variety of title translations (beyond the source language and the wiki's language) are provided, these should be items in a . ** Titles by region or language region should be separate, such as Spanish-language titles that are different in Spain and Latin America. This is because they are ultimately different pieces of data. ** A logo for a subject should be secondary to a textual representation of a title, so it should be either a secondary title or a . * handles feature-size images, and those images do not feature visible labels. ** Image fields only handle image data. Mixed image and text will show only the imagePortability principle: Don't mix data types in a single field. Text is text, images are images.. ** Image fields may contain either a or child to produce a tabbed gallery (or a slider gallery on mobile devices). Due to code simplicity, is preferred. Depending on how this feature is used, it may be required to change to using a parser function instead. Not all gallery properties that are available outside an infobox are available inside one, such as slideshows. ** The child tag handles captions. If an image field has a inside, the "caption" used for the gallery item becomes the tab label.Portability principle: change only one thing. The same action should not change multiple fields. ** Image fields do not require full File paths nor internal File: links, though they will accept them under most circumstances. However, any size or caption information added to the File: link will have no effect. ** Image fields will dynamically resize images (that are wider than 130px) to have the best fit on any platform, to a maximum of 270px – 300px. Smaller images, if they truly describe the subject of the infobox, will simply stay at their native size; if the smaller image is a game icon, or similar supplemental information, it should be a field instead. * is your typical area for most other parameters. * is a label-less area for arbitrary wikitext. ** Icons in the upper "title" area should be considered navigation, as they are neither explicitly a nor an . To achieve a good corner icon effect, place the and s inside a , with the first, and set .pi-group > .pi-navigation to float and clear. Groups Typical, vertical groups are easy to recognize. For horizontal groups, there are two choices: traditional "horizontal" layout, and "smart" groups. Each can be styled differently, if there is cause to do so, but there may be reasons to choose one or the other. Traditional horizontal groups are rigid, and are meant for a small and set number of items when there's little variation. For example, Previous & Next fields should use horizontal groups. They should be used on logical groups where the layout is a maximum of one layout row. Smart groups are meant for potentially larger, varied sets of items. They are responsive to the number of items, and will wrap each item to a new layout row when they reach the maximum number of items defined in the row-items group property. Data Labels Data labels can contain most wikitext. They should also respect (to clarify a label in a way that is not displayed, for editing purposes) and (to display parts of a label that should only appear in an article, not the editor). If they additionally contain an infoicon, they should be careful to avoid accessibility issuesTo avoid mixing text and images, infoicons should use Unicode characters when possible, such as ℹ️ (INFORMATION SOURCE, U+2139). This is an acceptable use of and title to convey non-obvious short descriptions, but can also be used to link to a more meaningful article.. Only items have visible labels. From a readability and accessibility perspective, it should be noted that vertically centered labels do not well define a taller data item, as the human eye tends to bounce around in unexpected ways. Also, short labels like "ATK" and "DEF" might make sense to an English-native reader, but should have use to help the comprehension of others that may be unfamiliar with either the topic or language. In contrast, very long labels without line breaks may be better simplified into smaller words. An equal width of label to value (i.e. 50% label width) is similarly less readable with vertical data items as it pulls away emphasis from the actual value (and usually adds colored whitespace), and should be avoided in new templates. If a label width must be increased, the proper CSS property is flex-basis. Step 5: Defaults and Formats It is typically a good idea to have the simplest input data to feed the template, reduced to a simple data-type (such as a number, strings of text, links, or lists of these). To that end, the tag can reshape raw input into formatted output. For example, an item with a cost of "10 gold" (assuming that "gold" is the only possible currency unit for that data value) can have the input of "10" and use the tag to show the visible value as "10 gold" (or use an in-game infoicon for gold, etc.). The tag can be used in the or tags, but not or . Default values with appear only when the article does not provide a value for the parameter named in source=. The tag can be used in the or or tags, but not . Default values should avoid "Unknown" or "-" type defaults unless they are required for layout. Portable Infoboxes are designed to not show values that are not used in an article's template call, so logic to hide it is not necessary; further, if no data items in a group are used, the group and its header will not appear unless the show="incomplete" attribute is added to the group. TIP: Automation is not always a good idea. On the surface, skipping the name or title in favor of the magic word is efficient, but can be problematic when the page name changes or is qualified or disambiguated or the title contains characters or markup that can't be duplicated with an article name. Having other elements, like images, dependent on page name can make things much more difficult if a community's users do not understand the inner magic and logic of your template for basic data entry or maintenance. Calling helper templates, Lua functions, or complex nested ParserFunctions all can contribute to user confusion if the templates ever need to be revised or untangled. If a data item needs no processing (i.e. only the } is used and not modified with functions or styling), the and tags do not need to be included at all. This function alone drastically simplifies some classic infoboxes upon migration. Otherwise, using and effectively is at the core of infobox migration, as many templates process TIP: If you are adding a category that is dependent on a value, declaring that Category in a switch here will save you from doing it later. Step 6: Styling Here is another area where classic infoboxes lose much of their bulk upon migration. Styling in PIs is accomplished using global CSS. Inline CSS (with the style and class attributes) is removed whenever possible. If all items of the same type are styled identically, these styles should be shifted to the default .portable-infobox CSS or a theme. If a value is styled differently from the others of its type (e.g. a Rōmaji transcription in italics next to kanji or kana), wikitext (e.g. ) or an appropriate HTML tag (e.g. ) used to offset them inside . Wikitext that does not use CSS is always considered portable. It is strongly suggested not to alter the width of infoboxes from the default using CSS, as images inside the infobox will begin to exceed the boundaries of the infobox. Images that are narrowed using CSS inevitably become distorted.There are methods using CSS to shorten an image that is taller than desired, such as max-height: 500px; width: auto; Theming and accent color Styling PI in CSS is a more complex topic than this guide allows for, but it is covered in some depth in . Bonus Step: Setting up central CSS and approving the Drafts have their own policies and procedures for approaching communities, but communities may choose to use many of the same tools and ideas that have proven effective. Dependent on the complexity of CSS and supporting code, a separate sandbox wiki is usually not necessary. Developing the template code directly on the main community using the Draft system is straightforward and makes testing the new template against existing articles easier, as it will provide as good or better results than a standalone testing wiki. The Draft system is very effective for being able to quickly test templates applied to a page, by previewing the page with '''/Draft added to the end of the template name. This is similar to using /sandbox. It works on all templates, not only infoboxes. Placing .portable-infobox and other PI-specific CSS in a separate stylesheet (MediaWiki:Themes.css) imported to MediaWiki:Wikia.css can also be helpful. The import line in the main skin stylesheet @import url("/load.php?mode=articles&articles=MediaWiki:Themes.css&only=styles"); will load the Themes.css in an optimized manner. Conclusion Porting classic infoboxes to PIs can make them much simpler for future maintenance, and allow for comprehensive style changes without recoding many templates. The language is designed to be both flexible and powerful. If you run into migration issues, feel free to get help on the Portability Hub or contacting a Vanguard member.